<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.		-*-Text-*- -->

<div class='chapter'>4. Strings</div><p class='cindent'><!-- string -->
	Strings are a type of array which are constants (they self-evaluate)
and have as their printed representation a sequence of characters enclosed
in quote marks, for example <font class="lisp">"foo bar"</font>.  Strings are the right data type
to use for text-processing.
	The functions described in this section provide a variety of
useful operations on strings.  Several of the functions actually work
on any type of 1-dimensional array and may be useful for other than string processing.
<font class="lisp">art-16b</font> arrays (arrays of 16-bit positive numbers) are often used
as strings; the extra bits allow for an expanded character set.
	In place of a string, most of these functions will accept a symbol or a fixnum
as an argument, and will coerce it into a string.  Given a symbol, its print name,
which is a string, will be used.  Given a fixnum, a 1 character long string
containing the character designated by that fixnum will be used.
	Note that the length of a string is computed using <font class="lisp">array-active-length</font>,
so that if a string has an array-leader, element 0 of the leader (called the
<font class="italic">fill pointer</font>) will be taken as the length.

	Since strings are arrays, the usual array-referencing function <font class="lisp">aref</font>
is used to extract the characters of the string as fixnums.  For example,
<pre class="lisp">
(aref "frob" 1) =&gt; 162  <font class="main">;lower-case r</font>
</pre>
It is also legal to store into strings (using <font class="lisp">aset</font>).
As with <font class="lisp">rplaca</font> on lists, this changes the actual object; one must be careful
to understand where side-effects will propagate to.

<div class='section'>4.1 String Manipulation</div>
<div class='defun'><font class='exdent'><font class='funcname'>character <font class='italic' color='purple'>x</font></font></font><br>
	<font class="lisp">character</font> coerces <font class="italic">x</font> to a single character,
represented as a fixnum.  If <font class="italic">x</font> is a number, it is returned.  If
<font class="italic">x</font> is a string or an array, its first element is returned.  If
<font class="italic">x</font> is a symbol, the first character of its pname is returned.
Otherwise, an error occurs.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>char-equal <font class='italic' color='purple'>ch1 ch2</font></font></font><br>
	This is the primitive for comparing characters for equality;
many of the string functions call it.  <font class="italic">ch1</font> and <font class="italic">ch2</font>
must be fixnums.  The result is <font class="lisp">t</font> if the characters are equal ignoring
case and font, otherwise <font class="lisp">nil</font>.
<font class="lisp">%%ch-char</font> is the byte-specifier for the portion of a character
which excludes the font information.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>char-lessp <font class='italic' color='purple'>ch1 ch2</font></font></font><br>
	This is the primitive for comparing characters for order;
many of the string functions call it.  <font class="italic">ch1</font> and <font class="italic">ch2</font>
must be fixnums.  The result is <font class="lisp">t</font> if <font class="italic">ch1</font> comes before <font class="italic">ch2</font>
ignoring case and font, otherwise <font class="lisp">nil</font>.
</div>

.defvar alphabetic-case-affects-string-comparison
This variable is normally <font class="lisp">nil</font>.  If it is <font class="lisp">t</font>, <font class="lisp">char-equal</font>,
<font class="lisp">char-lessp</font>, and the string searching and comparison functions will
distinguish between upper-case and lower-case letters.  It is alright
to bind this to <font class="lisp">t</font>, but changing its global value to <font class="lisp">t</font> will
break many system functions and user interfaces and so is not recommended.
.end_defvar

<div class='defun'><font class='exdent'><font class='funcname'>string <font class='italic' color='purple'>x</font></font></font><br>
	<font class="lisp">string</font> coerces <font class="italic">x</font> into a string.  Most of the string
functions apply this to their string arguments.
If <font class="italic">x</font> is a string or an array, it is returned.  If <font class="italic">x</font> is
a symbol, its pname is returned.  If <font class="italic">x</font> is a number, a 1-character
long string containing it is returned.  Otherwise, an error occurs.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-length <font class='italic' color='purple'>string</font></font></font><br>
	<font class="lisp">string-length</font> returns the number of characters in <font class="italic">string</font>.  This is 1
if <font class="italic">string</font> is a number, the <font class="lisp">array-active-length</font>
(see (array-active-length-fun))
if <font class="italic">string</font>
is an array, or the <font class="lisp">array-active-length</font> of the pname if <font class="italic">string</font> is a symbol.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-equal <font class='italic' color='purple'>string1 string2 &optional (idx1 0) (idx2 0) lim1 lim2</font></font></font><br>
	<font class="lisp">string-equal</font> compares two strings, returning <font class="lisp">t</font> if
they are equal and <font class="lisp">nil</font> if they are not.  The comparison ignores
the extra "font" bits in 16-bit strings
and ignores alphabetic case.  <font class="lisp">equal</font> calls <font class="lisp">string-equal</font> if
applied to two strings.
	The optional arguments <font class="italic">idx1</font> and <font class="italic">idx2</font> are the starting
indices into the strings.  The optional arguments <font class="italic">lim1</font> and <font class="italic">lim2</font>
are the final indices; the comparison stops just <font class="italic">before</font> the final index.
<font class="italic">lim1</font> and <font class="italic">lim2</font> default to the lengths of the strings.  These arguments are provided
so that you can efficiently compare substrings.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(string-equal "Foo" "foo") =&gt; t
(string-equal "foo" "bar") =&gt; nil
(string-equal "element" "select" 0 1 3 4) =&gt; t
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>%string-equal <font class='italic' color='purple'>string1 idx1 string2 idx2 count</font></font></font><br>
<font class="lisp">%string-equal</font> is the microcode primitive which <font class="lisp">string-equal</font> calls.
It returns <font class="lisp">t</font> if the <font class="italic">count</font> characters of <font class="italic">string1</font> starting
at <font class="italic">idx1</font> are <font class="lisp">char-equal</font> to the <font class="italic">count</font> characters of <font class="italic">string2</font>
starting at <font class="italic">idx2</font>, or <font class="lisp">nil</font> if the characters are not equal or
if <font class="italic">count</font> runs off the length of either array.

Instead of a fixnum, <font class="italic">count</font> may also be <font class="lisp">nil</font>.  In this case,
<font class="lisp">%string-equal</font> compares
the substring from <font class="italic">idx1</font> to <font class="lisp">(string-length <font class="italic">string1</font>)</font>
against the substring from <font class="italic">idx2</font> to <font class="lisp">(string-length <font class="italic">string2</font>)</font>.
If the lengths of these substrings differ, then they are not equal and
<font class="lisp">nil</font> is returned.

<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
<font class="main">To compare the two strings <font class="italic">foo</font> and <font class="italic">bar</font>:</font>
(%string-equal <font class="italic">foo</font> 0 <font class="italic">bar</font> nil)
<font class="main">To see if the string <font class="italic">foo</font> starts with the characters <font class="lisp">"bar"</font>:</font>
(%string-equal <font class="italic">foo</font> 0 "bar" 0 3)
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-lessp <font class='italic' color='purple'>string1 string2</font></font></font><br>
	<font class="lisp">string-lessp</font> compares two strings using dictionary order.
The result is <font class="lisp">t</font> if <font class="italic">string1</font> is the lesser, and <font class="lisp">nil</font>
if they are equal or <font class="italic">string2</font> is the lesser.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>substring <font class='italic' color='purple'>string start &optional end area</font></font></font><br>
	This extracts a substring of <font class="italic">string</font>, starting at the
character specified by <font class="italic">start</font> and going up to but not including
the character specified by <font class="italic">end</font>.  <font class="italic">start</font> and <font class="italic">end</font> are
0-origin indices.  The length of the returned string is <font class="italic">end</font> minus
<font class="italic">start</font>.  If <font class="italic">end</font> is not specified it defaults to the length
of <font class="italic">string</font>.  The area in which the result is to be consed may be
optionally specified.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(substring "Nebuchadnezzar" 4 8) =&gt; "chad"
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>nsubstring <font class='italic' color='purple'>string start &optional end area</font></font></font><br>
<font class="lisp">nsubstring</font> is the same as <font class="lisp">substring</font> except that the substring
is not copied; instead an indirect array (see <a href='fd_arr.html#indirect-array'>this link</a>) is created which shares part
of the argument <font class="italic">string</font>.  Modifying one string will modify the other.

Note that <font class="lisp">nsubstring</font> does not necessarily use less storage than
<font class="lisp">substring</font>; an <font class="lisp">nsubstring</font> of any length uses the same amount of
storage as a <font class="lisp">substring</font> 12 characters long.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-append <font class='italic' color='purple'>&rest strings</font></font></font><br>
Any number of strings are copied and concatenated into a single string.
With a single argument, <font class="lisp">string-append</font> simply copies it.
If the first argument is an array, the result will be an array of the same type.
Thus <font class="lisp">string-append</font> can be
used to copy and concatenate any type of 1-dimensional array.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(string-append 41 "foo" 41) =&gt; "!foo!"
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-trim <font class='italic' color='purple'>char-list string</font></font></font><br>
	This returns a <font class="lisp">substring</font> of <font class="italic">string</font>, with all characters
in <font class="italic">char-list</font> stripped off of the beginning and end.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(string-trim '(40) "  Dr. No  ") =&gt; "Dr. No"
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-left-trim <font class='italic' color='purple'>char-list string</font></font></font><br>
	This returns a <font class="lisp">substring</font> of <font class="italic">string</font>, with all characters
in <font class="italic">char-list</font> stripped off of the beginning.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-right-trim <font class='italic' color='purple'>char-list string</font></font></font><br>
	This returns a <font class="lisp">substring</font> of <font class="italic">string</font>, with all characters
in <font class="italic">char-list</font> stripped off of the end.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>char-upcase <font class='italic' color='purple'>ch</font></font></font><br>
	If <font class="italic">ch</font>, which must be a fixnum, is a lower-case alphabetic
character its upper-case form is returned; otherwise, <font class="italic">ch</font> itself is
returned.  If font information is present it is preserved.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>char-downcase <font class='italic' color='purple'>ch</font></font></font><br>
	If <font class="italic">ch</font>, which must be a fixnum, is a upper-case alphabetic
character its lower-case form is returned; otherwise, <font class="italic">ch</font> itself is
returned.  If font information is present it is preserved.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-upcase <font class='italic' color='purple'>string</font></font></font><br>
	Returns a copy of <font class="italic">string</font>, with all lower case alphabetic
characters replaced by the corresponding upper case characters.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-downcase <font class='italic' color='purple'>string</font></font></font><br>
	Returns a copy of <font class="italic">string</font>, with all upper case alphabetic
characters replaced by the corresponding lower case characters.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-reverse <font class='italic' color='purple'>string</font></font></font><br>
	Returns a copy of <font class="italic">string</font> with the order of characters reversed.
This will reverse a 1-dimensional array of any type.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-nreverse <font class='italic' color='purple'>string</font></font></font><br>
	Returns <font class="italic">string</font> with the order of characters reversed,
smashing the original string, rather than creating a new one.
If <font class="italic">string</font> is a number, it is simply
returned without consing up a string.
This will reverse a 1-dimensional array of any type.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-search-char <font class='italic' color='purple'>char string &optional (from 0) to</font></font></font><br>
<font class="lisp">string-search-char</font> searches through <font class="italic">string</font> starting at the index <font class="italic">from</font>,
which defaults to the beginning, and returns the index of the first
character which is <font class="lisp">char-equal</font> to <font class="italic">char</font>, or <font class="lisp">nil</font> if none is found.
If the <font class="italic">to</font> argument is supplied, it is used in place of <font class="lisp">(string-length <font class="italic">string</font>)</font>
to limit the extent of the search.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(string-search-char 101 "banana") =&gt; 1
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>%string-search-char <font class='italic' color='purple'>char string from to</font></font></font><br>
<font class="lisp">%string-search-char</font> is the microcode primitive which <font class="lisp">string-search-char</font>
and other functions call.  <font class="italic">string</font> must be an array and <font class="italic">char</font>, <font class="italic">from</font>,
and <font class="italic">to</font> must be fixnums.  Except for this lack of type-coercion, and the fact
that none of the arguments is optional, <font class="lisp">%string-search-char</font> is the same as
<font class="lisp">string-search-char</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-search-not-char <font class='italic' color='purple'>char string &optional (from 0) to</font></font></font><br>
<font class="lisp">string-search-not-char</font> searches through <font class="italic">string</font> starting at the index <font class="italic">from</font>,
which defaults to the beginning, and returns the index of the first
character which is <font class="italic">not</font> <font class="lisp">char-equal</font> to <font class="italic">char</font>, or <font class="lisp">nil</font> if none is found.
If the <font class="italic">to</font> argument is supplied, it is used in place of <font class="lisp">(string-length <font class="italic">string</font>)</font>
to limit the extent of the search.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(string-search-char 102 "banana") =&gt; 1
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-search <font class='italic' color='purple'>key string &optional (from 0) to</font></font></font><br>
<font class="lisp">string-search</font> searches for the string <font class="italic">key</font> in the string
<font class="italic">string</font>.  The search begins at <font class="italic">from</font>, which defaults to the
beginning of <font class="italic">string</font>.  The value returned is the index of the first
character of the first instance of <font class="italic">key</font>, or <font class="lisp">nil</font> if none is
found.
If the <font class="italic">to</font> argument is supplied, it is used in place of <font class="lisp">(string-length <font class="italic">string</font>)</font>
to limit the extent of the search.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(string-search "an" "banana") =&gt; 1
(string-search "an" "banana" 2) =&gt; 3
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-search-set <font class='italic' color='purple'>char-list string &optional (from 0) to</font></font></font><br>
<font class="lisp">string-search-set</font> searches through <font class="italic">string</font> looking for
a character which is in <font class="italic">char-list</font>.  The search begins at the index <font class="italic">from</font>,
which defaults to the beginning.  It returns the index of the first
character which is <font class="lisp">char-equal</font> to some element of <font class="italic">char-list</font>,
or <font class="lisp">nil</font> if none is found.
If the <font class="italic">to</font> argument is supplied, it is used in place of <font class="lisp">(string-length <font class="italic">string</font>)</font>
to limit the extent of the search.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(string-search-set '(116 117) "banana") =&gt; 2
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-search-not-set <font class='italic' color='purple'>char-list string &optional (from 0) to</font></font></font><br>
<font class="lisp">string-search-not-set</font> searches through <font class="italic">string</font> looking for
a character which is not in <font class="italic">char-list</font>.  The search begins at the index <font class="italic">from</font>,
which defaults to the beginning.  It returns the index of the first
character which is not <font class="lisp">char-equal</font> to any element of <font class="italic">char-list</font>,
or <font class="lisp">nil</font> if none is found.
If the <font class="italic">to</font> argument is supplied, it is used in place of <font class="lisp">(string-length <font class="italic">string</font>)</font>
to limit the extent of the search.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(string-search-not-set '(141 142) "banana") =&gt; 2
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-reverse-search-char <font class='italic' color='purple'>char string &optional from (to 0)</font></font></font><br>
<font class="lisp">string-reverse-search-char</font> searches through <font class="italic">string</font> in reverse order, starting
from the index one less than <font class="italic">from</font>, which defaults to the length of <font class="italic">string</font>,
and returns the index of the first character which is <font class="lisp">char-equal</font>
to <font class="italic">char</font>, or <font class="lisp">nil</font> if none is found.  Note that the index returned
is from the beginning of the string, although the search starts from the end.
If the <font class="italic">to</font> argument is supplied, it limits the extent of the search.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(string-reverse-search-char 156 "banana") =&gt; 4
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-reverse-search-not-char <font class='italic' color='purple'>char string &optional from (to 0)</font></font></font><br>
<font class="lisp">string-reverse-search-not-char</font> searches through <font class="italic">string</font> in reverse order, starting
from the index one less than <font class="italic">from</font>, which defaults to the length of <font class="italic">string</font>,
and returns the index of the first character which is <font class="italic">not</font> <font class="lisp">char-equal</font>
to <font class="italic">char</font>, or <font class="lisp">nil</font> if none is found.  Note that the index returned
is from the beginning of the string, although the search starts from the end.
If the <font class="italic">to</font> argument is supplied, it limits the extent of the search.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(string-reverse-search-not-char 101 "banana") =&gt; 4
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-reverse-search <font class='italic' color='purple'>key string &optional from (to 0)</font></font></font><br>
<font class="lisp">string-reverse-search</font> searches for the string <font class="italic">key</font> in the string <font class="italic">string</font>.
The search proceeds in reverse order, starting
from the index one less than <font class="italic">from</font>, which defaults to the length of <font class="italic">string</font>,
and returns the index of the first (leftmost) character of the first instance found,
or <font class="lisp">nil</font> if none is found.  Note that the index returned
is from the beginning of the string, although the search starts from the end.
The <font class="italic">from</font> condition, restated, is that the instance of <font class="italic">key</font> found
is the rightmost one whose rightmost character is before the <font class="italic">from</font>'th character
of <font class="italic">string</font>.
If the <font class="italic">to</font> argument is supplied, it limits the extent of the search.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(string-reverse-search "na" "banana") =&gt; 4
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-reverse-search-set <font class='italic' color='purple'>char-list string &optional from (to 0)</font></font></font><br>
<font class="lisp">string-reverse-search-set</font> searches through <font class="italic">string</font> in reverse order, starting
from the index one less than <font class="italic">from</font>, which defaults to the length of <font class="italic">string</font>,
and returns the index of the first character which is <font class="lisp">char-equal</font>
to some element of <font class="italic">char-list</font>, or <font class="lisp">nil</font> if none is found.
Note that the index returned
is from the beginning of the string, although the search starts from the end.
If the <font class="italic">to</font> argument is supplied, it limits the extent of the search.
<pre class="lisp">
(string-reverse-search-set '(141 142) "banana") =&gt; 5
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>string-reverse-search-not-set <font class='italic' color='purple'>char-list string &optional from (to 0)</font></font></font><br>
<font class="lisp">string-reverse-search-not-set</font> searches through <font class="italic">string</font> in reverse order, starting
from the index one less than <font class="italic">from</font>, which defaults to the length of <font class="italic">string</font>,
and returns the index of the first character which is not <font class="lisp">char-equal</font>
to any element of <font class="italic">char-list</font>, or <font class="lisp">nil</font> if none is found.
Note that the index returned
is from the beginning of the string, although the search starts from the end.
If the <font class="italic">to</font> argument is supplied, it limits the extent of the search.
<pre class="lisp">
(string-reverse-search-not-set '(141 156) "banana") =&gt; 0
</pre>
</div>

See also <font class="lisp">intern</font> ((intern-fun)), which given a string will return "the" symbol
with that print name.

<div class='section'>4.2 String Manipulation</div>
The special forms in this section allow you to create I/O streams which
input from or output to a string rather than a real I/O device.
See (streams) for documentation of I/O streams.

<div class="defspec"><font class='exdent'><font class='funcname'>with-input-from-string</font><font class="italic"> Special Form</font></font><br>
The form
<pre class="lisp">
(with-input-from-string (<font class="italic">var string</font>)
    <font class="italic">body</font>)
</pre>
evaluates the forms in <font class="italic">body</font> with the variable <font class="italic">var</font> bound to a stream
which reads characters from the string which is the value of the form
<font class="italic">string</font>.  The value of the special form is the value of the last
form in its body.

The stream is a "downward closure", so be careful what you do with it.
You cannot use it after control leaves the body, and you cannot nest
two <font class="lisp">with-input-from-string</font> special forms and use both streams
since the special-variable bindings associated with the stream will
conflict.  It is done this way to avoid any consing.

After <font class="italic">string</font> you may optionally specify two additional "arguments".
<pre class="lisp">
(with-input-from-string (<font class="italic">var string index</font>)
    <font class="italic">body</font>)
</pre>
uses <font class="italic">index</font> as the starting index into the string, and updates
it when it is done to the index of the first character not read (the
length of the string if all of it was read.)  Since <font class="italic">index</font> is
updated it may not be a general expression; it must be a variable
or a <font class="lisp">setf</font>-able reference.  The <font class="italic">index</font> is not updated
in the event of an abnormal exit from the body, such as a <font class="lisp">*throw</font>.

Use of the <font class="italic">index</font> feature prevents multiple values from being
returned out of the body, currently.

<pre class="lisp">
(with-input-from-string (<font class="italic">var string index limit</font>)
    <font class="italic">body</font>)
</pre>
uses the value of the form <font class="italic">limit</font> in place of the length of the
string if it is not <font class="lisp">nil</font>.  If you want to specify a <font class="italic">limit</font>
but not an <font class="italic">index</font>, put <font class="lisp">nil</font> for <font class="italic">index</font>.
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>with-output-to-string</font><font class="italic"> Special Form</font></font><br>
This special form provides a variety of ways to send output to a string
through an i/o stream.

<pre class="lisp">
(with-output-to-string (<font class="italic">var</font>)
  <font class="italic">body</font>)
</pre>
evaluates the forms in <font class="italic">body</font> with <font class="italic">var</font> bound to a stream
which saves the characters output to it in a string.  The value of
the special form is the string.

<pre class="lisp">
(with-output-to-string (<font class="italic">var string</font>)
  <font class="italic">body</font>)
</pre>
will append its output to the string which is the value of the form <font class="italic">string</font>.
(This is like the <font class="lisp">string-nconc</font> function.)
The value returned is the value of the last form in the body, rather than the string.
Multiple values are not returned.  If <font class="italic">string</font> has an array-leader,
element 0 of the array-leader will be used as the fill-pointer.  If <font class="italic">string</font>
is too small to contain all the output, <font class="lisp">adjust-array-size</font> will be used to
make it bigger.

<pre class="lisp">
(with-output-to-string (<font class="italic">var string index</font>)
  <font class="italic">body</font>)
</pre>
is similar to the above except that <font class="italic">index</font> is a variable or <font class="lisp">setf</font>-able
reference which contains the index of the next character to be stored into.
It must be initialized outside the <font class="lisp">with-output-to-string</font> and will be updated
upon normal exit.

The stream is a "downward closure", so be careful what you do with it.
You cannot use it after control leaves the body, and you cannot nest
two <font class="lisp">with-input-from-string</font> special forms and use both streams
since the special-variable bindings associated with the stream will
conflict.  It is done this way to avoid any consing.
</div>

<div class='section'>4.3 Maclisp-compatible Functions</div>
<div class='defun'><font class='exdent'><font class='funcname'>alphalessp <font class='italic' color='purple'>string1 string2</font></font></font><br>
<font class="lisp">(alphalessp <font class="italic">string1 string2</font>)</font> is equivalent to
<font class="lisp">(string-lessp <font class="italic">string1 string2</font>)</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>getchar <font class='italic' color='purple'>string index</font></font></font><br>
	Returns the <font class="italic">index</font>'th character of <font class="italic">string</font>
as a symbol.  Note that 1-origin indexing is used.  This function
is mainly for Maclisp compatibility; <font class="lisp">aref</font> should be used
to index into strings (however <font class="lisp">aref</font> will not coerce symbols
or numbers into strings).
</div>

<div class='defun'><font class='exdent'><font class='funcname'>getcharn <font class='italic' color='purple'>string index</font></font></font><br>
	Returns the <font class="italic">index</font>'th character of <font class="italic">string</font>
as a fixnum.  Note that 1-origin indexing is used.  This function
is mainly for Maclisp compatibility; <font class="lisp">aref</font> should be used
to index into strings (however <font class="lisp">aref</font> will not coerce symbols
or numbers into strings).
</div>

<div class='defun'><font class='exdent'><font class='funcname'>ascii <font class='italic' color='purple'>x</font></font></font><br>
	<font class="lisp">ascii</font> is like <font class="lisp">character</font>, but returns a symbol
whose printname is the character instead of returning a fixnum.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(ascii 101) =&gt; A
(ascii 56) =&gt; /.
</pre>
The symbol returned is interned in the <font class="lisp">user</font> package.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>maknam <font class='italic' color='purple'>char-list</font></font></font><br>
	<font class="lisp">maknam</font> returns
an uninterned symbol whose print-name is a string made up of the characters in <font class="italic">char-list</font>.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(maknam '(a b 60 d)) =&gt; ab0d
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>implode <font class='italic' color='purple'>char-list</font></font></font><br>
	<font class="lisp">implode</font> is like <font class="lisp">maknam</font> except that the returned symbol
is interned in the current package.
</div>

	The <font class="lisp">samepnamep</font> function is also provided; see (samepnamep-fun).

<div class='section'>4.4 Formatted Output</div><p class='cindent'><!-- formatted output -->
<!-- Should grind be in here? -->

<div class='defun'><font class='exdent'><font class='funcname'>format <font class='italic' color='purple'>destination control-string &rest args</font></font></font><br>
<font class="lisp">format</font> is used to produce formatted output.
<font class="lisp">format</font> outputs the characters of <font class="italic">control-string</font>, except
that a tilde ("~") introduces a directive.  The character after
the tilde, possibly preceded by arguments and modifiers, specifies
what kind of formatting is desired.  Some directives use one or more
elements of <font class="italic">args</font> to create their output.

	The output is sent to <font class="italic">destination</font>.  If <font class="italic">destination</font> is
<font class="lisp">nil</font>, a string is created which contains the output; this string is
returned as the value of the call to <font class="lisp">format</font>.  If <font class="italic">destination</font> is
a stream, the output is sent to it.  If <font class="italic">destination</font> is <font class="lisp">t</font>, the
output is sent to <font class="lisp">standard-output</font>.  If <font class="italic">destination</font> is a string
with an array-leader, such as would be acceptable to <font class="lisp">string-nconc</font>,
the output is added to the end of that string. 

	A directive consists of a tilde, optional decimal numeric parameters
separated by commas, optional colon ("<font class="lisp">:</font>") and atsign ("<font class="lisp">@</font>") modifiers,
and a single character indicating what kind of directive this is.
The alphabetic case of the character is ignored.
Examples of control strings:
<pre class="lisp">
"~S"        ; <font class="main">This is an S directive with no parameters.</font>
"~3,4:@s"   ; <font class="main">This is an S directive with two parameters, 3 and 4,</font>
            ; <font class="main">   and both the colon and atsign flags.</font>
</pre>

	Sometimes a numeric parameter is used to specify a character,
for instance the padding character in a right- or left-justifying
operation.  In this case a single quote ("<font class="lisp">'</font>") followed by the
desired character may be used as a numeric argument.  For example,
you can use
<pre class="lisp">
"~5,'0d"
</pre>
to print a decimal number in five columns with leading zeros.

	The kinds of directives will now be described.
<font class="italic">arg</font> will be used to refer to the next argument from <font class="italic">args</font>.
.table 3
.item ~D
<font class="italic">arg</font>, a number, is printed as a decimal integer.
<font class="lisp">~<font class="italic">n</font>D</font> uses a column width of <font class="italic">n</font>; spaces are inserted on
the left if the number requires less than <font class="italic">n</font> columns for its digits
and sign.  If the number doesn't fit in <font class="italic">n</font> columns, additional columns
are used as needed. <font class="lisp">~<font class="italic">n</font>,<font class="italic">m</font>D</font> uses <font class="italic">m</font> as the pad character
instead of 40 (space).  If <font class="italic">arg</font> is not a number, it is printed
in <font class="lisp">~A</font> format.
The <font class="lisp">@</font> modifier causes the number's sign to be printed always; the default
is only to print it if the number is negative.
The <font class="lisp">:</font> modifier causes commas to be printed between groups of three digits;
the third numeric parameter may be used to change the character used as the comma.
Thus the most general form of <font class="lisp">~D</font> is <font class="lisp">~<font class="italic">mincol</font>,<font class="italic">padchar</font>,<font class="italic">commachar</font>D</font>.
.item ~O
This is just like <font class="lisp">~D</font> but prints in octal instead of decimal.

.item ~F
<font class="italic">arg</font> is printed in floating point.  <font class="lisp">~<font class="italic">n</font>F</font> rounds <font class="italic">arg</font> to a precision
of <font class="italic">n</font> digits.  The minimum value of <font class="italic">n</font> is 2, since a decimal point is
always printed.  If the magnitude of <font class="italic">arg</font> is too large or too small, it is printed
in exponential notation.  If <font class="italic">arg</font> is not a number, it is printed in
<font class="lisp">~A</font> format.

.item ~E
<font class="italic">arg</font> is printed in exponential notation.  This is identical to <font class="lisp">~F</font>,
including the use of a numeric parameter to specify the number of digits,
except that the number is always printed with a trailing exponent,
even if it is within a reasonable range.

.item ~A
<font class="italic">arg</font>, any Lisp object, is printed without slashification (like <font class="lisp">princ</font>).
<font class="lisp">~:A</font> prints <font class="lisp">()</font> if <font class="italic">arg</font> is <font class="lisp">nil</font>; this is useful when printing
something that is always supposed to be a list.
<font class="lisp">~<font class="italic">n</font>A</font> inserts spaces on the right, if necessary, to make the
column width at least <font class="italic">n</font>.  The <font class="lisp">@</font> modifier causes the spaces
to be inserted on the left rather than the right.
<font class="lisp">~<font class="italic">mincol,colinc,minpad,padchar</font>A</font> is the full form of <font class="lisp">~A</font>,
which allows elaborate control of the padding.
The string is padded on the right with at least <font class="italic">minpad</font> copies
of <font class="italic">padchar</font>; padding characters are then inserted <font class="italic">colinc</font> characters
at a time until the total width is at least <font class="italic">mincol</font>.
The defaults are 0 for <font class="italic">mincol</font> and <font class="italic">minpad</font>, 1 for <font class="italic">colinc</font>,
and space for <font class="italic">padchar</font>.

.item ~S
This is just like <font class="lisp">~A</font>, but <font class="italic">arg</font> is printed <font class="italic">with</font> slashification
(like <font class="lisp">prin1</font> rather than <font class="lisp">princ</font>).

.item ~C
<font class="lisp">(character <font class="italic">arg</font>)</font> is printed as a keyboard character (see (%%kbd)).
Any control bits are printed first by representing them with Greek letters:
alpha (Control), beta (Meta), epsilon (Control and Meta),
lambda (Hyper), pi (Super).
If the character itself is alpha, beta, epsilon, lambda, pi, or equivalence-sign,
then it is preceded by an equivalence-sign to quote it.

With the colon flag (<font class="lisp">~:C</font>), the name of the control bits are spelled out
(e.g. "<font class="lisp">Control-Meta-F</font>"), and also non-printing characters (those in the 200 to 377 range)
are represented by their names (e.g. "<font class="lisp">Return</font>").

With both colon and atsign (<font class="lisp">~:@C</font>), the colon-only format is printed, and then
if the character requires the Top, Front, or Greek key(s) to type it,
this fact is mentioned (e.g. "<font class="lisp"> (Top-L)</font>").

For all three of these formats,
if the character is not a keyboard character but a mouse "character",
it is printed as "Mouse-", the name of the button, "-", and the number of clicks.

With just an atsign (<font class="lisp">~@C</font>), the character is printed in such a way that
the READ function can understand it, using "<font class="lisp">#/</font>" or "<font class="lisp">#\</font>".

Examples:
<pre class="lisp">
(setq a `(44 1440 403 215 611 ,(dpb 1 %%kbd-mouse 11)))
(format nil "~{&lt;~C&gt;~}" a)  =&gt;
  "&lt;$&gt;&lt; &gt;&lt;&gt;&lt;
&gt;&lt;	&gt;&lt;Mouse-Middle-Twice&gt;"
(format nil "~{&lt;~:C&gt;~}" a)  =&gt;
  "&lt;$&gt;&lt;Control-Meta-Space&gt;&lt;Control-&gt;&lt;Return&gt;&lt;Control-Tab&gt;&lt;Mouse-Middle-Twice&gt;"
(format nil "~{&lt;~:@C&gt;~}" a)  =&gt;
  "&lt;$&gt;&lt;Control-Meta-Space&gt;&lt;Control- (Top-X)&gt;&lt;Return&gt;&lt;Control-Tab&gt;&lt;Mouse-Middle-Twice&gt;"
(format nil "~{&lt;~@C&gt;~}" a)  =&gt;
  "&lt;#//$&gt;&lt;#\SPACE&gt;&lt;#//&gt;&lt;#\RETURN&gt;&lt;#\TAB&gt;&lt;#\MOUSE-M-2&gt;"
</pre>

.item ~%
Outputs a newline.  <font class="lisp">~<font class="italic">n</font>%</font> outputs <font class="italic">n</font> newlines.
No argument is used.

.item ~&
The <font class="lisp">:fresh-line</font> operation is performed on the output stream.
Unless the stream knows that it is already at the front of a line,
this outputs a newline.  <font class="lisp">~<font class="italic">n</font>&</font> does a <font class="lisp">:fresh-line</font> operation
and then outputs <font class="italic">n-1</font> newlines.

.item ~|
Outputs a formfeed.  <font class="lisp">~<font class="italic">n</font>|</font> outputs <font class="italic">n</font> formfeeds.  With a <font class="lisp">:</font>,
performs a <font class="lisp">:clear-screen</font> operation on the output stream if the stream
supports that operation; otherwise it behaves as if no <font class="lisp">:</font> were present
(outputs formfeed(s)).

.item ~X
Outputs a space.  <font class="lisp">~<font class="italic">n</font>X</font> outputs <font class="italic">n</font> spaces.

.item ~~
Outputs a tilde.  <font class="lisp">~<font class="italic">n</font>~</font> outputs <font class="italic">n</font> tildes.

.item ~ &lt;CR&gt;
Tilde immediately followed by a carriage return ignores the carriage return
and any whitespace at the beginning of the next line.  With a <font class="lisp">:</font>, the whitespace
is left in place.  With an <font class="lisp">@</font>, the carriage return is left in place.

.item ~*
<font class="italic">arg</font> is ignored.  <font class="lisp">~<font class="italic">n</font>*</font> ignores the next <font class="italic">n</font> arguments.
<font class="lisp">~:*</font> "ignores backwards"; that is, it backs up in the list
of arguments so that the argument last processed will be processed
again.  <font class="lisp">~:<font class="italic">n</font>*</font> backs up <font class="italic">n</font> arguments.
When within a <font class="lisp">~{</font> construct, the ignoring (in either direction)
is relative to the list of arguments being processed by the iteration.

.item ~P
If <font class="italic">arg</font> is not <font class="lisp">1</font>, a lower-case s is printed.  ("P" for "plural".)
<font class="lisp">~:P</font> does the same thing, after doing a <font class="lisp">~:*</font>; that is, it prints
a lower-case s if the <font class="italic">last</font> argument was not 1.  <font class="lisp">~@P</font> prints "y"
if the argument is 1, or "ies" if it is not.  <font class="lisp">~:@P</font> does the same thing,
but backs up first.

.item ~T
Spaces over to a given column.  <font class="lisp">~<font class="italic">n</font>,<font class="italic">m</font>T</font> will output
sufficient spaces to move the cursor to column <font class="italic">n</font>.  If the cursor
is already past column <font class="italic">n</font>, it will output spaces to move it to
column <font class="italic">n</font>+<font class="italic">mk</font>, for the smallest integer value <font class="italic">k</font> possible.
<font class="italic">n</font> and <font class="italic">m</font> default to <font class="lisp">1</font>.  Without the colon flag, <font class="italic">n</font> and
<font class="italic">m</font> are in units of characters; with it, they are in units of pixels.
<font class="italic">Note</font>: this operation <font class="italic">only</font> works properly on streams that support
the <font class="lisp">:read-cursorpos</font> and <font class="lisp">:set-cursorpos</font> stream operations
(see (read-cursorpos)).  On other streams (and when <font class="lisp">format</font> is creating
a string), any <font class="lisp">~T</font> operation will simply output two spaces.

.item ~R
If there is no parameter, then <font class="italic">arg</font> is printed as a cardinal English number, e.g. four.
With the colon modifier, <font class="italic">arg</font> is printed as an ordinal number, e.g. fourth.
With the atsign modifier, <font class="italic">arg</font> is printed as a Roman numeral, e.g. IV.
With both atsign and colon, <font class="italic">arg</font> is printed as an old Roman numeral, e.g. IIII.

If there is a parameter, then it is the radix in which to print the number.
The flags and any remaining parameters are used as for the <font class="lisp">~D</font> directive.
Indeed, <font class="lisp">~D</font> is the same as <font class="lisp">~10R</font>.  The full form here is therefore
<font class="lisp">~<font class="italic">radix</font>,<font class="italic">mincol</font>,<font class="italic">padchar</font>,<font class="italic">commachar</font>R</font>.

.item ~<font class="italic">n</font>G
"Goes to" the <font class="italic">n</font>th argument.  <font class="lisp">~0G</font> goes back to the
first argument in <font class="italic">args</font>.  Directives after a <font class="lisp">~<font class="italic">n</font>G</font>
will take sequential arguments after the one gone to.
When within a <font class="lisp">~{</font> construct, the "goto"
is relative to the list of arguments being processed by the iteration.
This is an "absolute goto"; for a "relative goto", see <font class="lisp">~*</font>.

.item ~[<font class="italic">str0</font>~;<font class="italic">str1</font>~;<font class="italic">...</font>~;<font class="italic">strn</font>~]
This is a set of alternative control strings.  The alternatives
(called <font class="italic">clauses</font>)
are separated by <font class="lisp">~;</font> and the construct is terminated by <font class="lisp">~]</font>.
For example, "<font class="lisp">~[Siamese ~;Manx ~;Persian ~;Tortoise-Shell ~;Tiger
~;Yu-Hsiang ~]kitty</font>".  The <font class="italic">arg</font>th
alternative is selected; <font class="lisp">0</font> selects the first.
If a numeric parameter is given (i.e. <font class="lisp">~<font class="italic">n</font>[</font>),
then the parameter is used instead of an argument
(this is useful only if the parameter is "<font class="lisp">#</font>").
If <font class="italic">arg</font> is out of range no alternative is selected.
After the selected alternative has been processed, the control string
continues after the <font class="lisp">~]</font>.

~[<font class="italic">str0</font>~;<font class="italic">str1</font>~;<font class="italic">...</font>~;<font class="italic">strn</font>~:;<font class="italic">default</font>~] has a default case.
If the <font class="italic">last</font> <font class="lisp">~;</font> used to separate clauses
is instead <font class="lisp">~:;</font>, then the last clause is an "else" clause,
which is performed if no other clause is selected.
For example, "<font class="lisp">~[Siamese ~;Manx ~;Persian ~;Tortoise-Shell ~;Tiger
~;Yu-Hsiang ~:;Unknown ~] kitty</font>".

~[~<font class="italic">tag00</font>,<font class="italic">tag01</font>,<font class="italic">...</font>;<font class="italic">str0</font>~<font class="italic">tag10</font>,<font class="italic">...</font>;<font class="italic">str1...</font>~]
allows the clauses to have explicit tags.  The parameters to each <font class="lisp">~;</font>
are numeric tags for the clause which follows it.  That clause is processed
which has a tag matching the argument.  If <font class="lisp">~:<font class="italic">a1</font>,<font class="italic">a2</font>,<font class="italic">b1</font>,<font class="italic">b2</font>,<font class="italic">...</font>;</font>
is used, then the following clause is tagged not by single values but
by ranges of values <font class="italic">a1</font> through <font class="italic">a2</font> (inclusive), <font class="italic">b1</font> through <font class="italic">b2</font>, etc.
<font class="lisp">~:;</font> with no parameters may be used at the end to denote a default clause.
For example, "<font class="lisp">~[~'+,'-,'*,'//;operator ~'A,'Z,'a,'z;letter ~'0,'9;digit ~:;other ~]</font>".

<font class="lisp">~:[<font class="italic">false</font>~;<font class="italic">true</font>~]</font> selects the <font class="italic">false</font> control string
if <font class="italic">arg</font> is <font class="lisp">nil</font>, and selects the <font class="italic">true</font> control string otherwise.

<font class="lisp">~@[<font class="italic">true</font>~]</font> tests the argument.  If it is not <font class="lisp">nil</font>,
then the argument is not used up, but is the next one to be processed,
and the one clause is processed.
If it is <font class="lisp">nil</font>, then the argument is used up, and the clause is not processed.
<pre class="lisp">
(setq prinlevel nil prinlength 5)
(format nil "~@[ PRINLEVEL=~D~]~@[ PRINLENGTH=~D]" prinlevel prinlength)
   =&gt;  " PRINLENGTH=5"
</pre>

.item ~;
Separates clauses in <font class="lisp">~[</font> and <font class="lisp">~&lt;</font> constructions.  It is undefined elsewhere.

.item ~]
Terminates a <font class="lisp">~[</font>.  It is undefined elsewhere.
.end_table

.item ~{<font class="italic">str</font>~}
This is an iteration construct.  The argument should be a list,
which is used as a set of arguments as if for a recursive call to <font class="lisp">format</font>.
The string <font class="italic">str</font> is used repeatedly as the control string.
Each iteration can absorb as many elements of the list as it likes.
If before any iteration step the list is empty, then the iteration is terminated.
Also, if a numeric parameter <font class="italic">n</font> is given, then there will be at most <font class="italic">n</font>
repetitions of processing of <font class="italic">str</font>.

<font class="lisp">~:{<font class="italic">str</font>~}</font> is similar, but the argument should be a list of sublists.
At each repetition step one sublist is used as the set of arguments for
processing <font class="italic">str</font>; on the next repetition a new sublist is used, whether
or not all of the last sublist had been processed.

<font class="lisp">~@{<font class="italic">str</font>~}</font> is similar to <font class="lisp">~{<font class="italic">str</font>~}</font>, but instead of
using one argument which is a list, all the remaining arguments
are used as the list of arguments for the iteration.

<font class="lisp">~:@{<font class="italic">str</font>~}</font> combines the features of <font class="lisp">~:{<font class="italic">str</font>~}</font> and <font class="lisp">~@{<font class="italic">str</font>~}</font>.
All the remaining arguments
are used, and each one must be a list.
On each iteration one argument is used as a list of arguments.

Terminating the repetition construct with <font class="lisp">~:}</font> instead of <font class="lisp">~}</font>
forces <font class="italic">str</font> to be processed at least once even if the initial
list of arguments is null (however, it will not override an explicit
numeric parameter of zero).

If <font class="italic">str</font> is null, then an argument is used as <font class="italic">str</font>.  It must be a string,
and precedes any arguments processed by the iteration.  As an example,
the following are equivalent:
<pre class="lisp">
(apply (function format) (list* stream string args))
(format stream "~1{~:}" string args)
</pre>
This will use <font class="lisp">string</font> as a formatting string.  The <font class="lisp">~1{</font> says it will
be processed at most once, and the <font class="lisp">~:}</font> says it will be processed at least once.
Therefore it is processed exactly once, using <font class="lisp">args</font> as the arguments.
As another example, the <font class="lisp">format</font> function itself uses <font class="lisp">format-error</font>
(a routine internal to the <font class="lisp">format</font> package) to signal
error messages, which in turn uses <font class="lisp">ferror</font>, which uses <font class="lisp">format</font> recursively.  
Now <font class="lisp">format-error</font> takes a string and arguments, just like <font class="lisp">format</font>,
but also prints some addtitional information: if the control string in <font class="lisp">ctl-string</font>
actually is a string (it might be a list -- see below), then it prints the string
and a little arrow showing where in the processing of the control string the
error occurred.  The variable <font class="lisp">ctl-index</font> points one character after the place of
the error.
<pre class="lisp">
(DEFUN FORMAT-ERROR (STRING &REST ARGS)
       (COND ((STRINGP CTL-STRING)
	      (FERROR NIL "~1{~:}~%~VT~%~3X/"~A/"~%"
		      STRING ARGS (+ CTL-INDEX 3) CTL-STRING))
	     (T (FERROR NIL "~1{~:}" STRING ARGS))))
</pre>
This first processes the given string and arguments using <font class="lisp">~1{~:}</font>, then
tabs a variable amount for printing the down-arrow, then prints the control
string between double-quotes.  The effect is something like this:
<pre class="lisp">
(format t "The item is a ~[Foo~;Bar~;Loser~]." 'quux)
&gt;&gt;ERROR: The argument to the FORMAT "~[" command must be a number
                   
   "The item is a ~[Foo~;Bar~;Loser~]."
...
</pre>

.item ~}
Terminates a <font class="lisp">~{</font>.  It is undefined elsewhere.
.end_table

.item ~^
This is an escape construct.  If there are no more arguments remaining
to be processed, then the immediately enclosing <font class="lisp">~{</font> or <font class="lisp">~&lt;</font> construct
is terminated.  (In the latter case, the <font class="lisp">~&lt; formatting <font class="italic">is</font> performed, but no
more clauses are processed before doing the justification.
The <font class="lisp">~^</font> should appear only at the <font class="italic">beginning</font> of a <font class="lisp">~&lt;</font> clause,
because it aborts the entire clause.  It may appear anywhere in a <font class="lisp">~{</font> construct.)
If there is no such enclosing construct, then the entire formatting operation
is terminated.

If a numeric parameter is given, then termination occurs if the parameter
is zero.  (Hence <font class="lisp">~^</font> is the same as <font class="lisp">~#^</font>.)  If two parameters are
given, termination occurs if they are equal.  If three are given, termination
occurs if the second is between the other two in ascending order.

If <font class="lisp">~^</font> is used within a <font class="lisp">~:{</font> construct, then it merely terminates
the current iteration step (because in the standard case it tests for
remaining arguments of the current step only); the next iteration step
commences immediately.  To terminate the entire iteration process,
use <font class="lisp">~:^</font>.

.item ~&lt;
<font class="lisp">~<font class="italic">mincol</font>,<font class="italic">colinc</font>,<font class="italic">minpad</font>,<font class="italic">padchar</font>&lt;<font class="italic">text</font>~&gt;</font>
justifies <font class="italic">text</font> within a field <font class="italic">mincol</font> wide.  <font class="italic">Text</font>
may be divided up into clauses with <font class="lisp">~;</font>--the
spacing is evenly divided between the text segments.
With no modifiers, the leftmost text segment is left justified in the
field, and the rightmost text segment right justified;  if there is
only one, as a special case, it is right justified.
The colon modifier causes
spacing to be introduced before the first text segment;  the atsign
modifier causes spacing to be added after the last.
<font class="italic">Minpad</font>, default <font class="lisp">0</font>, is the minimum number of <font class="italic">padchar</font>
(default space) padding characters to be output between each segment.
If the total width needed to satisfy these constraints is greater
than <font class="italic">mincol</font>, then <font class="italic">mincol</font> is adjusted upwards in
<font class="italic">colinc</font> increments.  <font class="italic">Colinc</font> defaults to <font class="italic">1</font>.
<pre class="lisp">
(format nil "~10&lt;foo~;bar~&gt;")    =&gt;  "foo    bar"
(format nil "~10:&lt;foo~;bar~&gt;")   =&gt;  "  foo  bar"
(format nil "~10:@&lt;foo~;bar~&gt;")  =&gt;  "  foo bar "
(format nil "~10&lt;foobar~&gt;")      =&gt;  "    foobar"
(format nil "$~10,,'*&lt;~3f~&gt;" 2.59023)  =&gt;  "$******2.59"
</pre>

If <font class="lisp">~^</font> is used within a <font class="lisp">~&lt;</font> construct, then only the clauses
which were completely processed are used.  For example:
<pre class="lisp">
(format nil "~15&lt;~S~;~^~S~;~^~S~&gt;" 'foo)            =&gt;  "            FOO"
(format nil "~15&lt;~S~;~^~S~;~^~S~&gt;" 'foo 'bar)       =&gt;  "BAR         FOO"
(format nil "~15&lt;~S~;~^~S~;~^~S~&gt;" 'foo 'bar 'baz)  =&gt;  "FOO   BAR   BAZ"
</pre>

If the first clause of a <font class="lisp">~&lt;</font> is terminated with <font class="lisp">~:;</font> instead of <font class="lisp">~;</font>,
then it is used in a special way.  All of the clauses are processed
(subject to <font class="lisp">~^</font>, of course), but the first one is omitted in
performing the spacing and padding.  When the padded result has been
determined, then if it will fit on the current line of output, it is output,
and the text for the first clause is discarded.  If, however, the padded text
will not fit on the current line, then a newline is output, then the
text for the first clause, then the padded text.  The first clause is
always processed, and so any arguments it refers to will be used;
the decision is whether to use the resulting piece of text, not whether to
process the first clause.  If the <font class="lisp">~:;</font> has a numeric parameter <font class="italic">n</font>, then
the padded text must fit on the current line with <font class="italic">n</font> character positions to spare
to avoid outputting the newline.
For example, the control string <font class="lisp">"~%;; ~{~&lt;;; ~:1; ~S~&gt;~^,~}.~%"</font> can be used to
print a list of items separated by commas, without breaking items over line boundaries,
and beginning each line with "<font class="lisp">;; </font>".  The argument 1 in <font class="lisp">~:1;</font> accounts
for the width of the comma which will follow the justified item if it is not the last
element in the list.  If <font class="lisp">~:;</font> has a second numeric parameter <font class="italic">m</font>,
then <font class="italic">m</font> is used as the width of the line, thus overriding the natural line
width of the output stream.  To make the preceding example use a line width of 50,
one would write <font class="lisp">"~%;; ~{~&lt;;; ~:1,30; ~S~&gt;~^,~}.~%"</font>.

.item ~&gt;
Terminates a <font class="lisp">~&lt;</font>.  It is undefined elsewhere.
.end_table

In place of a numeric parameter to a directive, you can put the letter
V, which takes an argument from <font class="italic">args</font> as a parameter to the
directive.  Normally this should be a number but it doesn't really have
to be.  This feature allows variable column-widths and the like.  Also,
you can use the character # in place of a parameter; it represents the
number of arguments remaining to be processed.  This is useful, for
example, for dealing with English conventions for printing lists:
<pre class="lisp">
(setq foo "Items:~#[ none~; ~S~; ~S and ~S~:;~@{~#[~1; and~] ~S~^,~}~].")
(format nil foo)  =&gt;  "Items: none."
(format nil foo 'foo)  =&gt;  "Items: FOO."
(format nil foo 'foo 'bar)  =&gt;  "Items: FOO and BAR."
(format nil foo 'foo 'bar 'baz)  =&gt;  "Items: FOO, BAR, and BAZ."
(format nil foo 'foo 'bar 'baz 'quux)  =&gt;  "Items: FOO, BAR, BAZ, and QUUX."
</pre>


	The user can define his own directives.  How to do this is not documented
here; read the code.  Names of user-defined directives longer than one character
may be used if they are enclosed in backslashes (e.g. <font class="lisp">~4,3\GRAPH\</font>).

<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(format nil "foo") =&gt; "foo"
(setq x 5)
(format nil "The answer is ~D." x) =&gt; "The answer is 5."
(format nil "The answer is ~3D." x) =&gt; "The answer is   5."
(setq y "elephant")
(format nil "Look at the ~A!" y) =&gt; "Look at the elephant!"
(format nil "The character ~:@C is strange." 1003)
      =&gt; "The character Meta- (Top-X) is strange."
(setq n 3)
(format nil "~D item~P found." n n) =&gt; "3 items found."
(format nil "~R dog~:[s are~; is~] here." n (= n 1))
      =&gt; "three dogs are here."
(format nil "~R dog~[~1; is~:;s are~] here." n)
      =&gt; "three dogs are here."
(format nil "Here ~[~1;is~:;are~] ~:*~R pupp~:P." n)
      =&gt; "Here are three puppies."
</pre>

<font class="lisp">format</font> also allows <font class="italic">control-string</font> to be a list of strings
and lists, which is processed from left to right.  Strings are interpreted
as in the simple case.  Lists are taken as extended directives; the first
element is the directive letter, and the remaining elements are the numeric
parameters to the directive.  If the
car of a list is not a recognized directive, the list is simply evaluated
as a form; anything it writes to the <font class="lisp">standard-output</font> stream will
appear in the result of <font class="lisp">format</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>format:print-list <font class='italic' color='purple'>destination element-format list &optional separator start-line options</font></font></font><br>
This function provides a simpler interface for the specific
purpose of printing comma-separated lists with no list element
split across two lines.  <font class="italic">destination</font> tells where to send the output;
it can be <font class="lisp">t</font>, <font class="lisp">nil</font>, or a stream, as with <font class="lisp">format</font>.
<font class="italic">element-format</font> is a format-control-string which tells how
to print each element of <font class="italic">list</font>; it is used as the body of a <font class="lisp">"~{...~}"</font> construct.
<font class="italic">separator</font>, which defaults to <font class="lisp">", "</font> (comma, space) is a string which goes after
each element except the last.  Format-control commands are not recommended in <font class="italic">separator</font>.
<font class="italic">start-line</font>, which defaults to three spaces, is a format-control-string which
is used as a prefix at the beginning of each line of output, except the first.
Format-control commands are allowed in <font class="italic">separator</font>, but they should not swallow
arguments from <font class="italic">list</font>.  <font class="italic">options</font> is a string inserted before the opening <font class="lisp">"{"</font>;
it defaults to the null string, but allows you to insert colon and/or atsign.
</div> 

For formatting Lisp code (as opposed to text and tables), there is
the Grind package.  See (grind).
.eof
</body>
</html>

